﻿//-----------------------------------------------------------------------
// <copyright file="IKeyboardInputHandler.cs" author="Artak Mkrtchyan">
//     Creative Commons - GNU General Public License (http://creativecommons.org/licenses/GPL/2.0/
// </copyright>
// <author>Artak Mkrtchyan</author>
// <email>mkArtak@gmail.com</email>
// <date>26/01/2013</date>
//-----------------------------------------------------------------------
using System;
using System.Collections.Generic;
using System.Windows.Input;

namespace ConsoleHoster.Common.UserInput
{
	public interface IKeyboardInputHandler
	{
		/// <summary>
		/// Registeres the specified method as a handler to the specified hit key set in the given context
		/// </summary>
		/// <param name="argHitKey">The <see cref="Key"/> which for register the handler</param>
		/// <param name="argHeldKeys">The key set which is should be in held state for the handler to activate</param>
		/// <param name="argContext">The context for which to activate the handler</param>
		/// <param name="argHandler">The logic to run, in case of registered key and context combination match.
		/// Note: Depending on the return value of the handler, it can decide whether to allow the key stroke event propagation through the handler stack or not.
		/// If the return value is true, the propagation will not run. To let the event to propogate - the handler should return false.</param>
		void RegisterHandler(Key argHitKey, IEnumerable<Key> argHeldKeys, string argContext, Func<IKeyboardStateProvider, bool> argHandler);

		/// <summary>
		/// Unregisters any registered handlers, matching the specified criteria
		/// </summary>
		/// <param name="argHitKey">The <see cref="Key"/> which for register the handler</param>
		/// <param name="argHeldKeys">The key set which is should be in held state for the handler to activate</param>
		/// <param name="argContext">The context for which to activate the handler</param>
		/// <returns>true, is a handler was found and unregistered. false, if the handler was not found.</returns>
		bool UnregisterHandler(Key argHitKey, IEnumerable<Key> argHeldKeys, string argContext);

		/// <summary>
		/// Looks for and invokes the registered key handler, if found.
		/// </summary>
		/// <param name="argHitKey">The hit key, which for to look for registered combinations</param>
		/// <param name="argContext">The context to look for registered handlers in</param>
		/// <returns>A boolean value, indicating whether the event was handled or not.
		/// If a registered handler is found, the deision about propogating the event
		/// further through the handlers is up to the registered handler.</returns>
		bool HandleKeyboardInput(Key argHitKey, string argContext);
	}
}
